[AI-Assisted] fix(compressor): report consistent speed-solve results and convergence - #4326

Master integration — 2026-10-15

Integrated head b172a1e153d0bab9313a6b4cdebe9054a5c1b76d incorporates master 420b4448a61cbb3e499e7a82cde5b1c996d7397c; verified tree b44348e6ff405c327b9ccbd2c2b824d06bdbf44e. Preserved both task-log entries and regenerated coverage. The compressor and optimizer implementation combines unchanged with the already merged mapped-network and shared mixing corrections. Validation includes compressor forward replay, bottleneck/flow optimization, mapped rejection and field-to-facility acceptance.

Validation: 65 focused tests passed, zero failures/errors/skips. Stable direct formatting, both hook stages, documentation search, regenerated coverage/check and whitespace checks passed. Documentation impact: retained the existing implementation guides and task-log entries from both branches; no new API, physics or tolerance change is introduced by this integration. Earlier evidence below applies to its recorded checkpoints. Integration follows the user's explicit instruction to merge in dependency order; new-head hosted CI is tracked separately.

Coordination and merge gates — 2026-10-14

Reviewed published head: 22d62de4f243d0a2ae7ee946f6621d02f9641776.

The integrated head preserves the original compressor/optimizer implementation and tests. Current Java 8 Ubuntu and Windows jobs remain active; the other checks pass. The corrected #4328 head has now passed an isolated combined 145-test trial with this head (one existing skip), replacing the earlier pending combined-trial claim. No human approval is recorded.

Require the process owner, independent compressor/optimization-domain review and independent maintainer coverage for the new diagnostics, exception subtype and solved() behavior. One qualified independent maintainer may satisfy both independent roles. Record compatibility classification; a bounded existing-method repair is not automatically an NRC, while an incompatible public failure contract would trigger one.

Integration: Prefer corrected #4328 first, then this PR, then repaired #4312. Retain actual fixed-speed replay, requested-target preservation and optimizer rejection of unconverged chart results in the combined tree.

Closes #4321.

Problem and evaluation

The issue reproduces on master 373f10eab27749a3fc7f7e9b022c3bcbdc65bc63 (3.25.0 sources). With the public synthetic chart, requested outlets of 6 and 8 bara were published unchanged while independent fixed-speed replay delivered 12.557809 and 12.331552 bara. Even the reachable 14 bara case published the setpoint rather than the computed 13.999581 bara.

Master already contains the accepted-root drift fix associated with #3896. This change preserves that behavior. Existing tests explicitly permit speed extrapolation with limitSpeed=false; the proposed fix preserves this compatibility instead of introducing an unconditional speed-bound exception.

Changes

• Track the best finite evaluated speed and evaluate the final state through the existing fixed-speed chart path. Outlet pressure, temperature, head and power now describe the reported speed, including guide-vane and anti-surge effects.
• Expose isSpeedSolveConverged() and getSpeedSolvePressureResidual() (achieved minus requested pressure, bar). Require the final forward result to satisfy the existing 0.001 bar tolerance.
• Propagate failed speed solves through solved(), isSimulationValid(), and getSimulationValidationErrors(). ProductionOptimizer now enforces the hard compressorSpeedSolve gate even with capacity analysis enabled or optional output validation disabled.
• Preserve the requested pressure, unit, calculation identifier and modes after both successful and limited/failed searches. Restore temporary modes in a finally block.
• Convert requested pressure to bara for the search; include speed bounds, limiting mode and pressure unit in recalculation-state tracking.
• Reject searches with no finite valid chart point instead of fabricating a target-pressure result. Failed searches with a valid iterate return its actual forward result and a warning.
• Add 13 regression cases covering the issue reproducer, state/power/temperature replay, convergence lifecycle, speed limits and extrapolation, MPa setpoints, both head units, guide vanes, anti-surge, cache invalidation and invalid inputs.
• Update the old speed-limit test to assert that its original target survives. The extreme-flow optimizer test now also recognizes the specific compressor invalid-map rejection, with matching unit name, cause and failed convergence/validation; unrelated exceptions are still rethrown.

CI repair and shared optimization fixes

The three current CI errors were reproduced on the original head: both professional lift-curve cases in FlowRateOptimizerTest and the compressor case in PressureBoundaryOptimizerTest.

• A failed chart trial now throws the specific Compressor.SpeedSolveException subtype. ProductionOptimizer records an infeasible candidate and continues searching without reading stale objectives/downstream constraints. Unrelated exceptions still propagate.
• The optimizer no longer lets capacity-analysis handling bypass a failed compressor pressure-target solve. The existing 0.001 bar tolerance is unchanged.
• FlowRateOptimizer reruns chart setup only when it actually generates a chart. Existing charts remain usable between tables even if the previous sweep ended at an invalid probe; this also removes redundant process runs.
• New regressions cover invalid-map candidate handling, stale-output prevention, mandatory convergence, recovery at a later valid point, and chart reuse. The existing extreme-flow rejection test now checks the narrower exception type and named compressor while retaining all physical-validity assertions.

Validation

Exact published head: c1a1796685c0225bb0dfef15f0d3e3861eba2acc. All 11 repair blobs were verified against locally validated Git blob hashes before the leased branch update.

OpenJDK 17.0.20; Java 8 source/target through pomJava8.xml:

• Original CI reproduction: 3 errors in the 3 failing optimizer methods before the repair.
• Final combined run: every Java test class selected by .github/workflows/practical-optimization-examples.yml, plus CompressorSpeedSolveConsistencyTest,CompressorChartSpeedInterpolationTest,CompressorChartTest,CompressorTest,CompressorTrainTest,CompressorShaftTest,CompressorInletGuideVaneTest,CompressorAntiSurgeControlLineTest,CompressorCurveOptimizationTest,CompressorChartReaderTest,BottleneckAnalysisOptimizerTest,ProductionOptimizerCompressorFailureTest, with -DexcludedTestGroups= -Djacoco.skip=true test: 485 tests, 0 failures, 0 errors, 1 pre-existing disabled network test; exit 0. This includes all 10 slow bottleneck tests and the existing unrelated-exception propagation regression.
• python3 devtools/run_spotless.py apply and check: exit 0; final formatter pass stable.
• python3 devtools/check_documentation_search.py: exit 0; 788 Markdown pages and 1 HTML page.
• pre-commit run --all-files --hook-stage pre-commit and --hook-stage pre-push: exit 0.
• python3 devtools/build_engineering_coverage.py --check and git diff --check: exit 0.
• ./mvnw -B -f pomJava8.xml -Dsubpackages=neqsim.process.equipment.compressor:neqsim.process.util.optimizer javadoc:javadoc, with an environment-only launcher for the installed JDK module: exit 0, existing documentation warnings.

Current CI and merge conditions are recorded above. Earlier validation below/above is evidence for the recorded source revision, not independent human approval.

Documentation impact and limits

Updated the compressor-curve and flow-rate optimization guides, exception/configuration/accessor Javadocs, compressor/anti-surge skill, task log and generated engineering-coverage inventory.

Read actual achieved pressure from the outlet stream; getOutletPressure() remains the requested setpoint. Pressure convergence does not certify mechanical feasibility when extrapolation is enabled. A failed local search is not proof of global infeasibility on a non-monotonic map. This change detects final pressure errors after anti-surge flow adjustment; it does not add a coupled speed/recycle optimizer.

AI-assisted implementation reviewed against the forward-model invariant: the same inlet, chart, options and returned speed must produce the same thermodynamic outlet and shaft power.

Shared thermodynamic foundation — #4333

The Windows Java 8 guide failure exposed a shared thermodynamic-state defect during parallel compressor train evaluation. The speed search and its forward replay could have identical chart flow, head, efficiency and speed but different heat-capacity ratios because classic mixing-rule calculations shared partial-sum fields.

This update incorporates the shared mixing-accumulator foundation. Its source and six deterministic SRK/PR regression cases are identical to the correction already included in #4306. No compressor algorithm, acceptance threshold, optimizer restriction or process limit is changed by this update.

All six interleaving cases fail without the foundation and pass with it. Applying only the corrected mixing-rule class to this PR removed 39 observed intermediate search/replay discrepancies; all four three-train guide examples remained feasible, including staged optimization. Mandatory formatting, pre-commit/pre-push, documentation search, generated coverage and whitespace gates pass on the incremental tree. Local numerical validation used Java 17 with Java 8 source/target; Windows Java 8 CI must requalify the published head.

Merge the shared foundation first, then retain the coordinated #4328 → #4326 → #4312 sequence with final-head checks between merges.

This PR is stacked on #4333. Retarget to master after that foundation merges; keep draft until the new head passes CI and the required independent reviews are recorded.